Ekahau RTLS Controller 5.6

Version: 5.6 - Date: Mar 24, 2011

1. Introduction
1.1. Overview
2. Web Services API
2.1. HTTP
2.2. XML
2.2.1. Binary
2.3. Authentication and Authorization
2.3.1. HTTP DIGEST Authentication
2.3.2. HTTP Negotiate Authentication
2.3.3. Authorization
2.4. Error Codes
2.5. Services
2.6. Event Service
2.7. Real-Time Streaming
2.8. Using Tag Groups
3. Object Model
3.1. Tag
3.2. Tag Configuration
3.3. Tag Menu
3.4. Tag Command
3.5. Tag Group
3.6. Tag Firmware
3.7. Tag Status
3.8. Asset
3.9. Asset Group
3.10. Model
3.11. Building & Map & Zone
3.12. Site
3.13. Event
3.14. Rule
3.15. User
3.16. Role
4. Ekahau RTLS Controller Java SDK
4.1. Setup
4.1.1. Installing
4.1.2. Running the Example
4.2. Files
4.3. SDK API
4.3.1. Packages
4.3.2. Essential Classes and Interfaces
4.4. Sample Code
4.5. Example Applications
5. Use Cases
5.1. Querying Locations
5.2. Tracking Tags in Real-Time
5.3. Receiving Button Events
5.4. Sending Tag Commands
5.5. Setting Custom Tag Properties
5.6. Browsing Model Content
5.7. Viewing Map Images
5.8. Viewing Routes
6. Tips
6.1. Learning API
6.2. Disabling Authentication
6.3. Compact Format for Stream Responses
6.4. API Timestamps
6.5. API Object Properties


1. Introduction

This document is targeted for application developers who use Ekahau RTLS Controller (ERC) web service API. This document does not explain tag interfaces. There is a separate document for tag hardware vendors.

1.1. Overview

The Ekahau Application Programming Interface (API) is based on HTTP/XML web service technology. This is a platform and language independent technology to expose services over the web. The number one goal in the design of the API has been simplicity, and you can actually test the API with a web browser without writing a single line of code.

Tip:

Go ahead and test the API with a web browser, go to address http://<server-ip>:8550/epe/developer

2. Web Services API

Ekahau API is built on the web services concept, its main building blocks being HTTP and XML. HTTP functions as the transport protocol, and XML defines the encoding scheme for the data. An API call is performed by making an HTTP request to a URL in the RTLS Controller. The request may contain input parameters. The RTLS Controller sends back a response, an XML document.

Ekahau API has similarities to XML-RPC and SOAP but does not conform to these two technologies. Ekahau API is a simplified version of XML-RPC, designed in the spirit of REST, which loosely defines how a web service can be crafted using clean URLs and clean XML documents. (Search the internet for these keywords to find out more.)

2.1. HTTP

HTTP provides the transport protocol for the API. Each URL in the RTLS Controller represents a separate API command and defines its own input parameters and response. All available URLs are located under the single root /epe/. URLs are documented in the online API Reference, served by a running RTLS Controller.

Ekahau API supports both HTTP GET and HTTP POST type requests. The difference is that an HTTP GET request has no enclosed XML document that describes the input parameters. In HTTP GET, the input parameters are provided with a standard HTTP query notation. The response from the RTLS Controller always contains an XML-document.

As an example, below you will find two identical requests, the first one via HTTP GET and the second one via HTTP POST. The calling method is different, but logically both the request and the RTLS Controller response are the same.

Example of a HTTP GET request: 

http://localhost:8550/epe/pos/taglist?fields=posgood&mapname=floor2

Example of an identical HTTP POST request; POST body as below: 

<?xml version="1.0" encoding="utf-8"?>
<request>
    <PARAMS>
        <fields>posgood</fields>
        <mapname>floor2</mapname>
    </PARAMS>
</request>

The HTTP protocol also requires the use of request headers, and provides response headers. Headers were omitted in these examples, as they are typically taken care of by the client library that implements HTTP.

RTLS Controller HTTP communication is completely stateless; no session concept nor cookies are in use. (Authentication may use cookies though.)

By default, Ekahau API uses TCP port 8550. The same port is used by the RTLS Controller administration web interface.

2.2. XML

XML is the primary data encoding scheme of Ekahau API. The RTLS Controller sends its response as an XML document. You may process the XML like any other XML document, using your favorite tools and parsers. There is no magic in the XML.

We have narrowed the hierarchy of XML documents to only two levels: at the top level you have objects (or messages), and each object may have properties underneath at a single level. Simpler XML documents make it easier to manipulate data in a program. XML element attributes (like <TAG attribute="nnn">) are not supported either.

Here's a possible answer for the /epe/pos/taglist request presented above. The RTLS Controller provides a list of tags that are located at map "floor2". 

<?xml version="1.0" encoding="utf-8"?>
<response>
    <TAG>
        <tagid>3003121670</tagid>
        <mac>00:00:B3:00:00:06</mac>
        <posx>240</posx>
        <posy>588</posy>
        <posmodelid>1</posmodelid>
        <posmapid>3</posmapid>
        <poszoneid>17</poszoneid>
        <posmapname>floor2</posmapname>
        <poszonename>hall-a</poszonename>
        <posquality>99</posquality>
        <posreason>1</posreason>
        <postime>1274253852001</postime>
        <postimestamp>2010-05-19 10:24:12+0300</postimestamp>
        <poscounter>656</poscounter>
        <battery>98</battery>
    </TAG>
    <TAG>
        <tagid>3003121666</tagid>
        <mac>00:00:B3:00:00:02</mac>
        <posx>67</posx>
        <posy>92</posy>
        <posmodelid>1</posmodelid>
        <posmapid>3</posmapid>
        <poszoneid>5</poszoneid>
        <posmapname>floor2</posmapname>
        <poszonename>reception</poszonename>
        <posquality>99</posquality>
        <posreason>1</posreason>
        <postime>1274254001591</postime>
        <postimestamp>2010-05-19 10:26:41+0300</postimestamp>
        <poscounter>1474</poscounter>
        <battery>0</battery>
    </TAG>
</response>

The response from the RTLS Controller starts with an XML preamble that specifies the character set for the XML document that follows. Currently Ekahau RTLS Controller always uses UTF-8, a popular encoding for unicode character sets directly supported by many tools.

Following the preamble is the root element <response>. The actual response is always enclosed inside <response>. Likewise, the requested XML document must always be enclosed inside <request>. (This root element included, the XML document is a maximum of three levels deep.)

2.2.1. Binary

The XML document may contain binary data as well. If the property ends with _b (as in data_b in /epe/mod/modeldownload), it contains binary data that is encoded as BASE64. Note that the Java SDK provided by Ekahau can automatically decode BASE64 data into binary format so you don't have to.

Further on, in some API calls, you may also request the binary data in its original format. In this case, the response contains just the binary data, and the response is NOT an XML document. See /epe/map/render for a good example.

2.3. Authentication and Authorization

Ekahau RTLS Controller authenticates all HTTP requests. Used authentication scheme depends on server configuration: currently RTLS Controller can be configured to support either HTTP DIGEST or HTTP Negotiate authentication scheme.

2.3.1. HTTP DIGEST Authentication

This is a standard mechanism for providing strong authentication while protecting users' passwords from eavesdropping.

In this mechanism, upon the first connection, the server sends a challenge to the client. The client then computes a digest, a checksum, for the challenge and user credentials, and sends the response back to the server for validation. In further requests, the client reuses the challenge to prevent network round trips. The specification of HTTP DIGEST is available in RFC 2617.

2.3.2. HTTP Negotiate Authentication

HTTP Negotiate authentication is used to authenticate users against an external user database such as Kerberos or Windows Active Directory.

In this mechanism the server requests the client to provide a Kerberos ticket to prove that the client principal is who he claims to be. The client gets the ticket from a Kerberos Key Distribution Center or a Windows Domain Controller. The ticket is sent to RTLS Controller in HTTP headers and a cookie is used to establish an authenticated session between the server and the client.

Many popular web browsers such as Internet Explorer and Mozilla Firefox support HTTP Negotiate authentication with Windows Active Directory out of the box. Ekahau Java SDK supports this authentication method as well.

2.3.3. Authorization

After the user has been authenticated, the request is still subject to authorization. Each API URL requires a certain role from the user. If the user's role is higher than or the same as the one required by the URL, the request is executed. If this is not the case, the request is declined with an access denied error. Roles are associated with users in the administrative interface or through the /epe/sys API.

In summary, authentication is the process of verifying who you are, and authorization is the process of verifying what you can do.

2.4. Error Codes

Ekahau API uses HTTP status codes to communicate errors in API calls. All the standard status codes from 1xx to 5xx are in use. In addition to these standard status codes, Ekahau has defined its own status codes in the 6xx range.

The most common status codes are:

Full list of standard HTTP status codes are available in RFC 2616.

2.5. Services

The API has been grouped into several logical services, each having their own functionality.

The following list of services is in rough order of importance. Broadly speaking, the topmost services /epe/pos , /epe/eve , /epe/status , /epe/route and /epe/sensor produce most of the output that applications use while the following two services /epe/msg and /epe/cfg are used to send commands to tags. The rest of the services are mainly needed for configuring and maintaining the system.

Note that while all the services expose some calls in the HTTP interface, they may also have functionality that doesn't show up in the HTTP interface. For example, /epe/tag and /epe/rec implement protocols for Ekahau tags. Their main functionality is available via these protocols; HTTP is just used to provide status information for applications.

2.6. Event Service

The event service (/epe/eve) is a major subsystem that deserves a more elaborate description than other API services.

The event service has two basic functions: First, provides event notifications in real-time with the help of event stream when defined event rule conditions are met. Secondly, it stores the history of events in case they are found interesting at some later time. Real-time notifications are received with the /epe/eve/eventstream command, while history can be queried with the /epe/eve/historylist command. The service also includes commands for defining and maintaining rules that generate events.

One of the use cases for events is to receive a certain subset of new locations from the RTLS Controller, basically in the same way one can do with /epe/pos/tagstream. In this comparison the event service is more advanced, the rules are stored and can be easily reused and shared between applications. The fundamental difference between defining event rules and calling tagstream with parameters is that event history is recorded.

A basic rule for filtering location events is created by specifying one or more scanreasons (button, tamper sensor etc), possibly with other parameters such as taggroupid. If the zoneid or mapid parameters are given in rule creation, also modelid is required. In this case, if the active model is a different one, the rule will not produce any events. This protects from accidentally getting false events when the active model is changed and map and zone ids are used differently in the new model.

There are also other, more exciting types of rules. You can receive an event whenever a tag enters or exits a map or a zone. The key parameter here is entermapid , exitmapid , enterzoneid or exitzoneid . The enter/exit rules require that a modelid is specified in rule creation, with the same reasoning and consequences as with scanreason rules.

When using the presence feature, rules can be defined for tracking the presence of tags. Such a rule is created with the entersiteid or exitsiteid parameters.

Furthermore, you can create a rule with the lowbatterylimit or highbatterylimit parameters to receive events from important changes in tags' battery levels. These events lack location data, but they do carry other properties of the tag.

Finally, there are built-in rules called system rules. The following system rules come built-in with RTLS Controller:

System rules are designed to help applications stay up-to-date with the status of the RTLS Controller. E.g. when the active model is changed, an application that receives the resulting event can take action to refresh its own state to be consistent with the new model.

As is already mentioned, all events are recorded into a history record. Note that this happens independently of event streams. All active rules are continuously recording event history, no matter if they are being used in event streaming or not. By default, 500,000 most recent events are stored. When this limit is reached, new events start to overwrite the oldest ones.

2.7. Real-Time Streaming

HTTP is typically a request-response protocol. You request something from the server, and the server sends a single response to you. To request more, you'll do another request and the server will send another response, and so on. For most purposes, this is fine.

Most of the API calls in RTLS Controller fall into the above category. Exceptions are the stream commands /epe/pos/tagstream, /epe/eve/eventstream, /epe/status/statusstream, /epe/route/routestream and /epe/sensor/sensorstream. By calling these commands, your connection stays up forever and you'll receive multiple responses for a single request. New locations or events are sent to you immediately as the server calculates them.

Take advantage of the streaming features whenever you need real-time access to data that RTLS Controller provides, or when your application needs to stay aware of what is happening in the server. Do not poll /epe/pos/taglist to keep up with changes in locations; it is much more efficient to listen to a stream.

2.8. Using Tag Groups

RTLS Controller is capable of producing masses of location update events, especially when there are thousands of tags in the system. The concept of tag groups is designed to help limit and filter the data that an application receives from the server. You can for example let the user track the locations of only a specific group of tags at a time by using the taggroupid parameter with /epe/pos/tagstream. In the same way, /epe/pos/taglist can be called to query the latest locations of a group of tags. And when defining event rules, tag groups can be of great use to get events only from the relevant tags.

The creation of a tag group is simple, the /epe/cfg/taggroupcreate command needs just a name and an optional description for the group, and it returns a unique ID allocated for the new group. Tags are added to groups with the /epe/cfg/tagaddtogroup command and removed with /epe/cfg/tagremovefromgroup. A tag can belong to an unlimited number of groups at the same time.

A typical use for tag groups is some categorization of the assets tags are attached to, but they can be used in any way that is found meaningful.

3. Object Model

The logical object model of Ekahau RTLS Controller positioning system is explained here. Understanding the objects and their relations is necessary for the effective use of the API. (And the product!)

3.1. Tag

Tag is any entity which can be positioned with RTLS Controller. The term "tag" actually refers to a compact piece of hardware that is attached to an asset, but in the API a tag object is used to represent any device whose location, sensor data or status is tracked. Tag objects are returned from the /epe/pos/taglist and /epe/pos/tagstream API commands. In addition, many events from the /epe/eve interface contain information about a tag related to the event.

A tag's location is always given as coordinates on some map. Additionally, if the tag's location is inside a zone, the tag object carries also this information. And beyond location information, tags have other properties, like type, name and battery level.

Only the latest location, the latest filtered location and the latest button location are stored in a tag's properties. New values overwrite previous ones. (On a side note, route service captures the location history of the tags for a longer time.)

3.2. Tag Configuration

Tag Configuration is a list of configuration commands to be sent to a tag to control its behavior. Each tag may have zero or one configuration. A single tag configuration can be associated with multiple tags.

The configuration commands can be modified at any time. Whenever a configuration is modified, tags will get the new commands as soon as they contact the server. See maintenance interval below.

There are separate configurations for T201, T301 and T301i tags as well as Software Client devices. A T301 configuration is applicable to most T301 subtypes such as T301A, T301B and T301W.

Sensor devices such as T301t may have various calibration parameters that are saved in the RTLS Controller database. Number and types of parameters depend on the sensor type.

3.3. Tag Menu

Display-equipped devices such as the T301B tag can be configured with a menu. A menu has a list of zero or more items. In RTLS Controller's object model an item is simply a string; this string is the label that is displayed on a tag's display when the menu is viewed. A menu also has a name and an optional description.

Menus are managed exactly in the same way as tag configurations. A menu can be assigned to multiple tags, and RTLS Controller remembers these associations. If a menu is modified, the modification is sent to all tags with an association to the menu (as with configurations).

When a menu item is selected, the device sends a location update carrying the index of the selected item. Application can receive menu selection events in real time via tagstream or eventstream, or later by using the taglist and historylist APIs.

3.4. Tag Command

A command is an ASCII-string. RTLS Controller has a private command queue for each tag. Commands are added to the queue through API, and are picked by the tag at periodic intervals. This maintenance interval is specified in the tag's configuration. Tags pick both private and configuration commands during a maintenance call.

There is a separate command language for the T301 family and the older T201. Furthermore, different versions of T301 tags support different command sets. For these reasons a tag's type is important when sending commands to it. See tag user guides for a list of valid commands.

3.5. Tag Group

Tag groups are optional groupings of tags. A tag may belong to many groups and a group may contain many tags.

Deleting a group does not delete the tags in the group.

3.6. Tag Firmware

The software inside a tag can be updated over the air via the RTLS Controller. The tag software is packaged as a firmware image file by Ekahau. Once Ekahau has provided a new firmware file, the customer can upload it to the RTLS Controller, and command tags in his environment to switch to the new firmware.

Different tag types have their own firmware images that are not compatible with each other.

3.7. Tag Status

A tag may have zero or more status values, one for each status type. Different status types serve different applications and their possible values are not limited. Typical status type would be TagActivity which indicates whether the tag has been active or not. TagActivity status type has possible values Active and Inactive.

Tag status objects disappear when the tag is removed from the system, but all status changes are recorded in the status history. Most tag status types require system configuration by administrator before they can be used.

3.8. Asset

An asset typically represents a real-life entity that is tracked with RTLS Controller.

Assets are created and deleted using the Asset service. Every asset is uniquely identifier by its ID. A tag can be bound to a single asset and an asset can have only one tag bound to it at a time. Bindings can be changed any time, which is immediately reflected in events and history lists.

3.9. Asset Group

Asset groups are optional groupings of assets, similar to tag groups. An asset may belong to many groups and a group may contain many assets.

3.10. Model

A model is a file that contains the logical structure of the building or area where the tags are being positioned. Models are created with the Ekahau Site Survey application. A model is required by the RTLS Controller positioning algorithm which calculates tag positions based on the data in the model. The model directly affects the accuracy of calculated positions.

Multiple model files can be stored in the RTLS Controller, but only a single model can be active at a time. Whenever a new model is uploaded to the RTLS Controller, it will get a unique id.

3.11. Building & Map & Zone

A model may be divided into multiple buildings each containing a number of maps. A map usually corresponds to a floor in a building. A map may be further divided into multiple logical areas, known as zones. Buildings, maps and zones are created with the Ekahau Site Survey application during model creation. A position calculated by the RTLS Controller has x,y-coordinates on a certain map, and specifies also a zone if the tag is inside one.

Maps and zones have unique identifiers and names within a single model. Identifiers in different models may overlap. However, Ekahau Site Survey makes sure that existing map and zone identifiers do not change during model modification .

3.12. Site

The concept of site goes with the presence feature and is similar to the concepts of map and zone in a positioning model. A presence model defines a number of sites where tags can be present.

Unlike with positioning, there are no x,y-coordinates, nor are there map images. Basically the only properties associated with a site are its name and unique identifier. Also the raw data used for presence evaluation (IP address of the tag or associated access point MAC address) is bundled to a site object when RTLS Controller reports a tag's presence.

3.13. Event

An event is something that happens in the RTLS Controller and is important or interesting to some application. There are many types of events. For example a SCAN event is generated when a tag provides a set of Wi-Fi access point scan results (leading to the calculation of a new location) that fulfills some criteria.

The data contained in an event object varies depending on its type. A SCAN event contains the same data as a tag object (see above). An example of a simpler event is the ACTIVEMODELCHANGED type, which contains only the id of the new active model. All events also have a timestamp and a reference to the rule that generated them.

Events have two different uses. One is a notification from RTLS Controller to an application that something interesting has just happened (using event stream). Secondly, all events are recorded into a history record, from which an application can search for important events that have happened in the past. In both cases the event object has essentially the same format; the only difference is that events received from a stream are missing a dedicated unique id (this is allocated when the event is stored in database). Streamed events can still be uniquely identified by the combination of rule id and timestamp.

3.14. Rule

A rule is a definition of criteria for some class of events. Rules are used to filter important events from unimportant ones; only the important ones are delivered to applications. In our vocabulary, an event is generated by a rule when it is found to be "important" (i.e. it fulfills the criteria of the rule).

An application can create its own rules to receive events that it finds interesting. These rules are classified as "USER" rules. There is a complete description of available rule creation parameters with lots of examples in the online API reference. Another class of rules is called "SYSTEM". System rules have a simple, fixed criteria for generating events, and they are readily built into RTLS Controller.

A rule can be disabled, which stops it from generating events until enabled again. User rules can also be permanently deleted. Note that deleting a rule does not delete its event history. If a rule needs to be completely erased including its history, there is an operation called purge that does this.

Rules can be given a string property called label , which is meant to work as a loose grouping of rules. Rules having the same label can be used as one group when opening an event stream or querying history.

3.15. User

RTLS Controller requires user authentication for each API call and each call to the web administration application. A user is designated a single role.

There is a single database of users for both API and the administration user interface (UI). In other words, the administration UI is just an application using the same API, and it too must provide API credentials.

3.16. Role

A role defines what a user can do in the RTLS Controller. Four roles have been defined. From the highest to the lowest they are administrator , poweruser , tagoperator and viewer . Roles are cumulative, a higher role includes the privileges of lower ones.

Each API call requires a specified role. In order to pass access control, the caller must possess the specified role or a higher role.

4. Ekahau RTLS Controller Java SDK

Most programming languages and tools already support web service technologies: HTTP communication and XML document parsing. There are also numerous open source and commercial tools and libraries that can help in using web service APIs such as the Ekahau RTLS Controller API.

If you are familiar with your own tools, and especially if you don't code in Java, go ahead and start making the positioning killer application with the standard tools you have. If you code in Java, you might want to check out Ekahau RTLS Controller Java SDK.

Ekahau RTLS Controller Java SDK provides a quick and easy out-of-the-box solution for calling the Ekahau RTLS Controller API from Java language. The SDK is a simple messaging library containing just a few top-level classes. It automatically parses XML documents into convenient messaging objects, takes care of HTTP DIGEST or Negotiate authentication, knows how to call the streaming API (HTTP/1.1 chunked transfer) and encodes/decodes BASE64 data correctly so you don't have to.

Included in the SDK are sample applications that demonstrate the use of SDK and API.

Full source code of the SDK is included for those who like to study the SDK or port it to another language. The SDK itself uses a few good open source libraries.

4.1. Setup

4.1.1. Installing

Install the SDK by running the setup program. The program will ask the installation folder where all the development files will be installed to.

You also have to install the Java SE Development Kit (JDK), which is not included in the setup program. Ekahau RTLS Controller Java SDK requires at least JDK 1.4.2.

4.1.2. Running the Example

After installation, run example.bat to verify success. The program should print out usage instructions.

Run example.bat list to get the list of tags in the RTLS Controller that is running on the local machine. If the RTLS Controller runs on a different machine, specify its address. Also specify alternative user credentials if necessary.

If both commands succeeded, both Java SDK and the RTLS Controller were successfully installed.

4.2. Files

The SDK contains the following files:

4.3. SDK API

The SDK consists of a number of Java packages and example applications.

4.3.1. Packages

The SDK API is divided into following packages:

4.3.2. Essential Classes and Interfaces

Core classes (found in the com.ekahau.common.sdk package):

Supplementary classes (found in the com.ekahau.engine.sdk, com.ekahau.engine.sdk.event, com.ekahau.engine.sdk.status com.ekahau.engine.sdk.route and com.ekahau.engine.sdk.sensor packages):

4.4. Sample Code

Here's a very simple but functional example application that lists all the tags and their positions using the SDK. The application prints all the received properties of each tag in its own line. 

import java.util.*;
import com.ekahau.engine.sdk.*;

public class SdkTestProgram {
    public static void main(String[] args) throws EngineException {
        PositioningEngine engine = new PositioningEngine();
        List devices = engine.findDevices();
        Iterator it = devices.iterator();
        while (it.hasNext()) {
            DeviceLocation d = (DeviceLocation) it.next();
            System.out.println(d);
        }
    }
}

4.5. Example Applications

There are a number of example applications included with the SDK, in the com.ekahau.engine.sdk.examples package. They demonstrate the usage of RTLS Controller through the SDK in some typical use cases. Use their source code as a reference on how to get started with your own application.

5. Use Cases

This chapter presents a few typical use cases of the RTLS Controller and it's API.

5.1. Querying Locations

How to get the latest locations of all tags in the RTLS Controller?

RTLS Controller stores the latest locations of tags in a database. They can be queried with /epe/pos/taglist. This is a very powerful call with many input parameters. It can potentially return a huge amount of data. fields is a parameter that controls how much information the call returns for each tag.

To get the latest locations, we specify fields=posgood. That is, we want those properties that concern a tag's latest "good" position: 

http://localhost:8550/epe/pos/taglist?fields=posgood

The response XML is similar to the one in chapter 2.2.

Often it is desirable to list the tags in the order of activity. To get the tags in the order of "tag with most recent position" first, "tag with oldest position" last, call: 

http://localhost:8550/epe/pos/taglist?fields=posgood&orderby=lastpos&ascending=false

A position is flagged as "good" when the positioning algorithm thinks that the probability of it is good enough. When the probability is low, the position is filtered out and flagged as "failed". Also failed positions can be queried from the RTLS Controller, but they should not be used for positioning since they are not trustworthy. They may be applicable for troubleshooting purposes.

How to get the latest locations of tags in a given floor?

In addition to the above, we need to specify a search condition: 

http://localhost:8550/epe/pos/taglist?fields=posgood&mapid=45

The above returns tags on floor with the map id 45. One can also search by map name: 

http://localhost:8550/epe/pos/taglist?fields=posgood&mapname=lobby

How to get the latest locations where a button was pressed? 

http://localhost:8550/epe/pos/taglist?fields=posbutton

5.2. Tracking Tags in Real-Time

How to track tags in real-time?

To receive new tag positions in real-time, call: 

http://localhost:8550/epe/pos/tagstream

New positions start flowing to the caller. The call never returns. Technically, there is a standard HTTP/1.1 chunked transfer transport. Make sure your tool supports it. (Ekahau Java SDK supports it.)

If you only want to track a few tags, do specify a filter to limit the amount of data sent over the network: 

http://localhost:8550/epe/pos/tagstream?tagid=3003121600,3003121605

Note that it is better to start one bigger stream rather than many small ones. Each active stream connection consumes resources at the RTLS Controller.

Note:

Every tagstream location response has a posfilter element which defines whether or not the location tracking algorithm qualified the location estimate as an accurate location. The location quality filter settings are defined and tested when the positioning model is created. Therefore location estimates which are labeled as 'failed' should not be used or displayed in the application, since the assumed poor accuracy may cause undesired events to take place within the application.

Where can I get tag serial number with real-time tracking?

Tagstream messages do not contain all of the tags' properties. Properties such as serial number and software version are excluded from the stream.

You can retrieve the missing tag properties via /epe/pos/taglist. Do a big taglist query in your application in the beginning and store the data in memory, in a map data structure, for example. Then start the stream. When you receive a real-time position, fetch the other tag properties from the map.

The device info changed system rule can be used to stay up to date if, for instance, the software version of a tag changes. RTLS Controller will in this case send an event to anyone who is listening to this rule with /epe/eve/eventstream. It is generally a good idea to listen to all system events to stay synchronized with changes taking place in RTLS Controller.

Warning:

To get other (static) tag properties, do not call /epe/pos/taglist?tagid=nnn for each received position event from /epe/pos/tagstream! This will slow the system down. Cache infrequently changing data in memory.

5.3. Receiving Button Events

How to track button events in real-time?

You can open a tagstream so that it only outputs positions that are sent to RTLS Controller because of a button press. Scanreasons 1, 6 and 8 mean different buttons:

http://localhost:8550/epe/pos/tagstream?scanreason=1,6,8

Another option is to create a rule for button events and then listen to events of that rule using eventstream: 

http://localhost:8550/epe/eve/rulecreate?name=mybuttonrule&scanreason=1,6,8
http://localhost:8550/epe/eve/eventstream?ruleid=<id returned from rulecreate>

An important difference between using tagstream and eventstream is that events are also stored in the event history record. This can be useful or not, depending on your application's needs.

5.4. Sending Tag Commands

How to send commands to tags?

Commands can not be sent immediately. Tags are not on-the-air constantly. Most of the time they are in a sleeping mode, saving battery. Tags poll the RTLS Controller for new commands every now and then; the frequency is set by the maintenance interval (it can be just about anything from a few seconds to days). The interval is determined during the deployment of the RTLS and depends on the environment and the requirements set for positioning. The more often a tag polls the RTLS Controller, the quicker its battery runs out.

Commands are put into a queue where they are picked up by a tag when it comes to request them. Here's an example of adding a command to a tag's queue: 

http://localhost:8550/epe/cfg/tagcommandadd?tagid=nn&cmd=sendinfo

How do I know when commands are picked up by a tag?

RTLS Controller includes a built-in event rule device commands sent . It produces an event whenever RTLS Controller sends commands to a tag from the pending commands queue. All commands in a tag's queue are sent at once.

The device commands sent rule is one of the built-in system rules that are designed to help applications stay in sync with the RTLS Controller. It is a good idea to listen to all system events by opening an event stream with the class=system parameter: 

http://localhost:8550/epe/eve/eventstream?class=system

How to play the buzzer?

With the T301 tag and other devices compatible with Ekahau Maintenance Protocol, the buzzer is played with commands mmm and mmt. To play the buzzer once, call: 

http://localhost:8550/epe/cfg/tagcommandadd?tagid=nn&cmd=mmm 0&cmd=mmt 1

T201 has a different syntax for commands. To play a T201's buzzer, call: 

http://localhost:8550/epe/cfg/tagcommandadd?tagid=nn&cmd=buzzer duration 5

How to handle a button event from a T301i tag?

T301i works in a special way when its button is pressed. It sends a normal button event to RTLS Controller (which can be captured in an application like any button event), but at the same time the tag enters active state, where it frequently checks for new commands. This frequency (i.e. maintenance interval in active state) can be configured with the mna command.

You can communicate with the tag's user by sending led commands. While the tag is in active state, it picks up the commands quickly and the communication is nearly delayless. A typical use case for leds is that the tag's user can be notified about the processing status of an order or request that she made by pressing the button.

When the event is completely handled, send me 0 to put the tag back to idle state.

5.5. Setting Custom Tag Properties

How to set custom properties for tags?

There are two fields in the basic tag properties that can be written through the API: name and custom.

name is a name associated with the tag. The maximum length is 100 chars. Name is displayed on the tags-page of the web administration.

custom is a custom data field associated with the tag. The maximum length is 50 chars. Custom field is not displayed on the main tags-page of the web administration.

To set name and custom fields, call 

http://localhost:8550/epe/cfg/tagsetname?tagid=nn&name=mary&custom=color_5;symbol_12

Using tag attributes for storing custom data

There is also a more advanced feature for custom properties that is called tag attributes. An attribute is a simple key-value pair of strings where key can be up to 100 characters long and value up to 300 characters. There can be an unlimited number of attributes for a single tag. Use /epe/cfg/tagsetattribute to add, modify and delete tag attributes and /epe/pos/taglist?fields=attribute to retrieve them.

Note: T201 tags supported user fields in their own memory. T301 tags do not provide memory for user fields.

Also consider grouping tags into tag groups to mark a set of tags for some purpose.

5.6. Browsing Model Content

How to find out what is in a model?

Assuming the model has been uploaded to the RTLS Controller, call: 

http://localhost:8550/epe/mod/modelbrowse?modelid=nn

The call will return all buildings, map ids, map names, zone ids and zone names that exist in the given model. It also returns the polygon coordinates for zones.

You should cache the response if you want to access it frequently. The call may take some time for a large model.

Of course, Ekahau Site Survey offers best ways to browse, visualize, and manipulate positioning models.

5.7. Viewing Map Images

How to see where a tag is on a map?

The RTLS Controller can quickly draw and place tags on the map. To see where the tag named "mary" is, just call: 

http://localhost:8550/epe/map/render?name=mary&format=png

The above returns a PNG image of a map with a blue circle marking the location of the tag.

Note: If another model was just activated in the RTLS Controller, the tag's location may still be in the old model. In this case, drawing the map takes a longer time. Maps from the active model are returned faster because the active model is cached internally by the RTLS Controller.

5.8. Viewing Routes

How do I draw the route a tag has taken?

RTLS Controller records routes of tracked devices. To retrieve whole route for a certain device, just call: 

http://localhost:8550/epe/route/routehistorybrowse?tagid=nn

The API command accepts many parameters such as time intervals and tag group ids that affect which route points are returned.

The accuracy of route calculation naturally depends on the configuration of tags, i.e. how often and when they report new locations.

6. Tips

This chapter describes miscellaneous tips and best practices for developing applications for the Ekahau RTLS Controller.

6.1. Learning API

To help you in understanding the API, you might want to observe how Ekahau's own applications are calling the API. This can be accomplished easily. We'll just make the RTLS Controller log all the API requests: 

http://localhost:8550/epe/sys/logsetlevel?category=epe.api&level=INFO

Or, if you want to log the RTLS Controller responses as well (actually just the first object of the response): 

http://localhost:8550/epe/sys/logsetlevel?category=epe.api&level=DEBUG

Now, when you use the web administration or any other application, you'll see all the API requests (and responses) in the log file.

Ekahau RTLS Controller provides extensive logging features. All the major components can provide information for troubleshooting and monitoring purposes. See the system service for logging options.

6.2. Disabling Authentication

To ease application development, you may turn authentication off while developing your application. Here's how to do it:

Warning:

It is highly recommended that authentication is enabled in production setups.

6.3. Compact Format for Stream Responses

In addition to XML, the RTLS Controller also supports a compact format for responses from /epe/pos/tagstream, /epe/eve/eventstream, /epe/status/statusstream, /epe/route/routestream and /epe/sensor/sensorstream calls. An advantage of using compact format is that parsing a compact response can be many times faster than parsing XML.

Compact format has the same logical structure (same objects and their properties) as XML but is expressed in a more terse way. Each object and its properties are expressed in a single line which ends with CR or CR+LF. Each property is encoded as propertyname=valuelength:value. Strings are encoded using UTF-8.

Here's the same response as in section 2.2 but in compact format: (Lines are cut with \ for display purposes only; the real response only contains two lines.) 

TAG tagid=10:3003121670 mac=17:00:00:B3:00:00:06 posx=3:240 posy=3:588 posmodelid=1:1 posmapid=1:3 \
 poszoneid=2:17 posmapname=6:floor2 poszonename=6:hall-a posquality=2:99 posreason=1:1 \
 postime=13:1274253852001 postimestamp=24:2010-05-19 10:24:12+0300 poscounter=3:656 battery=2:98
TAG tagid=10:3003121666 mac=17:00:00:B3:00:00:02 posx=2:67 posy=2:92 posmodelid=1:1 posmapid=1:3 \
 poszoneid=1:5 posmapname=6:floor2 poszonename=9:reception posquality=2:99 posreason=1:1 \
 postime=13:1274254001591 postimestamp=24:2010-05-19 10:26:41+0300 poscounter=4:1474 battery=1:0
Tip:

If there is a lot of activity in the RTLS Controller, parsing the XML in the client may require lots of processing power. To speed up real-time streaming, use compact format by specifying format=compact in the /epe/pos/tagstream, /epe/eve/eventstream, /epe/status/statusstream, /epe/route/routestream and /epe/sensor/sensorstream calls. The Java SDK knows how to parse compact responses. Create an EStreamConnection passing false to the constructor.

6.4. API Timestamps

All timestamps returned by the API are expressed in the RTLS Controller local time. Timestamps include the time zone information. Timestamps are formatted in both human ("timestamp") and machine ("time") readable formats as can be seen from the example reponse in 2.2.

Timestamps are formatted according to ISO 8601 format: YYYY-MM-DD HH:MM:SSZ. For example, May 29, 2010 at 3:44:16 PM in the Eastern Standard Time (EST, GMT-5), is encoded as 2010-05-29 15:44:16-0500.

Machine readable time is expressed as milliseconds elapsed since midnight UTC of January 1, 1970. For example the time of the previous example would be encoded as 1275165856000.

6.5. API Object Properties

If a property of an object is empty, it is not included in the XML response sent by the RTLS Controller.

© 2006-2011 by Ekahau, Inc.